Typical HAL SMARTCARD use cases for migration

This section provides information about typical HAL SMARTCARD use cases for migration.

Note

The processes for transmitting and receiving data using polling, interrupt, or DMA remain unchanged in HAL1 and HAL2.

Note

In both HAL1 and HAL2, the size parameter in the transmit and receive APIs represents the amount of data in bytes.

Use case: SMARTCARD communication in polling mode

Sequence diagram

SMARTCARD communication in polling mode

@startuml participant "Application" as p1 participant "HAL Smartcard driver" as p2 == initialization and configuration == == Smartcard Processing in polling mode == alt polling p1->p2: HAL_SMARTCARD_Transmit(&hsmartcard,\n aTxBuffer,\n DATA_TO_SEND_SIZE,\n 1000) note over p2 #00FF00 Transmitting data ongoing end note p2-->p1: <color #Green> HAL_OK else p1->p2: HAL_SMARTCARD_Receive(&hsmartcard,\n aRxBuffer,\n DATA_TO_RECEIVE_SIZE,\n 1000) note over p2 #00FF00 Receiving data ongoing end note p2-->p1: <color #Green> HAL_OK end @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE           256
#define DATA_TO_RECEIVE_SIZE       DATA_TO_SEND_SIZE

uint8_t aTxBuffer[] = " **** Smartcard Communication **** ";
uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

SMARTCARD_HandleTypeDef hsmartcard;


HAL_SMARTCARD_Init(&hsmartcard);




HAL_SMARTCARD_Receive(&hsmartcard, aRxBuffer,
                      DATA_TO_RECEIVE_SIZE, 1000);

HAL_SMARTCARD_Transmit(&hsmartcard, aTxBuffer,
                       DATA_TO_SEND_SIZE, 1000);

#define DATA_TO_SEND_SIZE           256
#define DATA_TO_RECEIVE_SIZE       DATA_TO_SEND_SIZE

uint8_t aTxBuffer[] = " **** Smartcard Communication **** ";
uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

hal_smartcard_handle_t hsmartcard;
hal_smartcard_config_t smartcard_config;

HAL_SMARTCARD_Init(&hsmartcard, HAL_SMARTCARD4);

/* add config for smartcard instance */
HAL_SMARTCARD_SetConfig(&hsmartcard, &smartcard_config);

HAL_SMARTCARD_Receive(&hsmartcard, aRxBuffer,
                      DATA_TO_RECEIVE_SIZE, 1000);

HAL_SMARTCARD_Transmit(&hsmartcard, aTxBuffer,
                       DATA_TO_SEND_SIZE, 1000);

Key changes

  1. The polling transmit/receive process is unchanged between HAL1 and HAL2.

  2. HAL2 introduces the handle/config model and requires configuring the SMARTCARD instance before communication.

Use case: SMARTCARD RX IT process

Sequence diagram

SMARTCARD receive IT process

@startuml participant " Application" as p1 participant "HAL SMARTCARD driver" as p2 participant "SMARTCARD_IRQHandler" as p3 == initialization and configuration == == Smartcard HAL Receive IT == p1->p2: <color: green> HAL_SMARTCARD_Receive_IT(&hsmartcard, aRxBuffer, DATA_TO_RECEIVE_SIZE) note over p2 #00FF00 Receiving data ongoing end note p2-->p1: HAL_OK p3<-: SMARTCARD data interrupt p3->p2: HAL_SMARTCARD_IRQHandler note over p2 #FFFF99 All data (Size == hsmartcard->RxXferCount) have been received end note note over p2 #00FF00 End of receiving data end note p2->p1: HAL_SMARTCARD_RxCpltCallback(hsmartcard->RxXferCount) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_RECEIVE_SIZE       256

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

SMARTCARD_HandleTypeDef hsmartcard;


/* Ensure that all required peripherals
  (USART, GPIO, NVIC etc.) are configured properly
/*
...
*/

/* Smartcard register Receive complete user callback */
HAL_SMARTCARD_RegisterCallback(&hsmartcard, HAL_SMARTCARD_RX_CB_ID,
                               Smartcard_RxCpltCallback);

/* Start a Smartcard Process in interruption mode */
HAL_SMARTCARD_Receive_IT(&hsmartcard, aRxBuffer,
                        DATA_TO_RECEIVE_SIZE);

#define DATA_TO_RECEIVE_SIZE       256

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];

hal_smartcard_handle_t hsmartcard;


/* Ensure that all required peripherals
  (USART, GPIO, NVIC etc.) are configured properly
/*
...
*/

/* Smartcard register Receive complete user callback */
HAL_SMARTCARD_RegisterRxCpltCallback(&hsmartcard, Smartcard_RxCpltCallback);


/* Start a Smartcard Process in interruption mode */
HAL_SMARTCARD_Receive_IT(&hsmartcard, aRxBuffer,
                        DATA_TO_RECEIVE_SIZE);

Key changes

  1. HAL2 uses the SMARTCARD handle type hal_smartcard_handle_t.

  2. HAL2 provides a dedicated receive-complete callback registration API (HAL_SMARTCARD_RegisterRxCpltCallback).

Use case: SMARTCARD TX IT process

Sequence diagram

SMARTCARD transmit IT process

@startuml participant " Application" as p1 participant "HAL SMARTCARD driver" as p2 participant "SMARTCARD_IRQHandler" as p3 == initialization and configuration == == Smartcard HAL Transmit IT == p1->p2: <color: green> HAL_SMARTCARD_Transmit_IT(&hsmartcard, aTxBuffer, DATA_TO_SEND_SIZE) note over p2 #00FF00 Transmitting data ongoing end note p2-->p1: HAL_OK p3<-: SMARTCARD data interrupt p3->p2: HAL_SMARTCARD_IRQHandler note over p2 #FFFF99 All data (Size == hsmartcard->TxXferCount) have been transmitted end note note over p2 #00FF00 End of transmitting data end note p2->p1: HAL_SMARTCARD_TxCpltCallback(hsmartcard->TxXferCount) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE       256

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** Smartcard Communication **** ";

SMARTCARD_HandleTypeDef hsmartcard;


/* Ensure that all required peripherals
  (USART, GPIO, NVIC etc.) are configured properly
/*
...
*/

/* Smartcard register Transmit complete user callback */
HAL_SMARTCARD_RegisterCallback(&hsmartcard, HAL_SMARTCARD_TX_CB_ID,
                               Smartcard_TxCpltCallback);

/* Start a Smartcard Process in interruption mode */
HAL_SMARTCARD_Transmit_IT(&hsmartcard, aTxBuffer,
                        DATA_TO_SEND_SIZE);

#define DATA_TO_SEND_SIZE       256

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** Smartcard Communication **** ";

hal_smartcard_handle_t hsmartcard;


/* Ensure that all required peripherals
  (USART, GPIO, NVIC etc.) are configured properly
/*
...
*/

/* Smartcard register Transmit complete user callback */
HAL_SMARTCARD_RegisterTxCpltCallback(&hsmartcard, Smartcard_TxCpltCallback);


/* Start a Smartcard Process in interruption mode */
HAL_SMARTCARD_Transmit_IT(&hsmartcard, aTxBuffer,
                        DATA_TO_SEND_SIZE);

Key changes

  1. HAL2 uses the SMARTCARD handle type hal_smartcard_handle_t.

  2. HAL2 provides a dedicated transmit-complete callback registration API (HAL_SMARTCARD_RegisterTxCpltCallback).

Use case: SMARTCARD RX DMA process

Sequence diagram

SMARTCARD receive DMA process

@startuml participant " Application" as p1 participant "HAL SMARTCARD driver" as p2 participant "DMA" as p3 participant "DMAx_IRQHandler" as p4 == initialization and configuration == == Smartcard HAL Receive DMA == p1->p2: <color: green> HAL_SMARTCARD_Receive_DMA(&hsmartcard, aRxBuffer, DATA_TO_RECEIVE_SIZE) note over p2 #00FF00 Receiving data ongoing end note p2->p3: HAL_DMA_Start_IT() p3-->p2: HAL_OK p2-->p1: HAL_OK p4<-: DMAx complete interrupt p4->p3: HAL_DMA_IRQHandler note over p3 #00FF00 End of receiving data end note p3->p2: XferCpltCallback p2->p1: HAL_SMARTCARD_RxCpltCallback(hsmartcard->rx_xfer_count) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_RECEIVE_SIZE  255

SMARTCARD_HandleTypeDef hsmartcard;

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];


/* Ensure that all required peripherals
(USART, GPIO,NVIC,DMA etc.) are configured properly
/*
...
*/

/* Smartcard register Receive complete user callback */
HAL_SMARTCARD_RegisterCallback(&hsmartcard, HAL_SMARTCARD_RX_CB_ID,
                               Smartcard_RxCpltCallback);

/* Start a Smartcard Process in dma mode */
HAL_SMARTCARD_Receive_DMA(&hsmartcard, aRxBuffer,
                             DATA_TO_RECEIVE_SIZE)

#define DATA_TO_RECEIVE_SIZE  255

hal_smartcard_handle_t hsmartcard;

uint8_t aRxBuffer[DATA_TO_RECEIVE_SIZE];


/* Ensure that all required peripherals
  (USART, GPIO,NVIC,DMA etc.) are configured properly
/*
...
*/

/* Smartcard register Receive complete user callback */
HAL_SMARTCARD_RegisterRxCpltCallback(&hsmartcard, Smartcard_RxCpltCallback);


/* Start a Smartcard Process in dma mode */
HAL_SMARTCARD_Receive_DMA(&hsmartcard, aRxBuffer,
                         DATA_TO_RECEIVE_SIZE)

Key changes

  1. HAL2 uses a different DMA start API for peripheral transfers (HAL_DMA_StartPeriphXfer_IT_Opt).

  2. HAL2 provides a dedicated receive-complete callback registration API (HAL_SMARTCARD_RegisterRxCpltCallback).

Use case: SMARTCARD TX DMA process

Sequence diagram

SMARTCARD transmit DMA process

@startuml participant "User Application" as p1 participant "HAL SMARTCARD driver" as p2 participant "SMARTCARD_IRQHandler" as p5 participant "DMA" as p3 participant "DMAx_IRQHandler" as p4 == initialization and configuration == == Smartcard HAL Transmit DMA == p1->p2: <color: green> HAL_SMARTCARD_Transmit_DMA(&hsmartcard, aTxBuffer, DATA_TO_SEND_SIZE) note over p2 #00FF00 Transmitting data ongoing end note p2->p3: HAL_DMA_Start_IT() p3-->p2: HAL_OK p2-->p1: HAL_OK p4<-: DMAx complete interrupt p4->p3: HAL_DMA_IRQHandler note over p3 #00FF00 End of transmitting data end note p3->p2: XferCpltCallback p2->p2: Enable SMARTCARD Transmit Complete IRQ (TCIE) p5<-: SMARTCARD Transmit Complete (TCIE) p5->p2: HAL_SMARTCARD_IRQHandler p2->p1: HAL_SMARTCARD_TxCpltCallback(hsmartcard->tx_xfer_count) @enduml

Code snippet

HAL1

HAL2 

#define DATA_TO_SEND_SIZE  255

SMARTCARD_HandleTypeDef hsmartcard;

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** Smartcard Communication **** ";


    /* Ensure that all required peripherals
      (USART, GPIO,NVIC,DMA etc.) are configured properly
    /*
    ...
    */

    /* Smartcard register Transmit complete user callback */
    HAL_SMARTCARD_RegisterCallback(&hsmartcard, HAL_SMARTCARD_TX_CB_ID,
                                   Smartcard_TxCpltCallback);

    /* Start a Smartcard Process in dma mode */
    HAL_SMARTCARD_Transmit_DMA(&hsmartcard, aTxBuffer,
                                    DATA_TO_SEND_SIZE)

#define DATA_TO_SEND_SIZE  255

hal_smartcard_handle_t hsmartcard;

uint8_t aTxBuffer[DATA_TO_SEND_SIZE] = " **** Smartcard Communication **** ";


    /* Ensure that all required peripherals
      (USART, GPIO,NVIC,DMA etc.) are configured properly
    /*
    ...
    */

    /* Smartcard register Transmit complete user callback */
    HAL_SMARTCARD_RegisterTxCpltCallback(&hsmartcard, Smartcard_TxCpltCallback);


    /* Start a Smartcard Process in dma mode */
    HAL_SMARTCARD_Transmit_DMA(&hsmartcard, aTxBuffer,
                                    DATA_TO_SEND_SIZE);

Key changes

  1. HAL2 uses a different DMA start API for peripheral transfers (HAL_DMA_StartPeriphXfer_IT_Opt).

  2. HAL2 provides a dedicated transmit-complete callback registration API (HAL_SMARTCARD_RegisterTxCpltCallback).